home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-11 / shd11a.zip / SHADOW.DOC < prev    next >
Text File  |  1993-04-26  |  16KB  |  609 lines
  1. **************
  2. * ShadowLink *
  3. **************
  4. Version 1.1 Demo
  5.  
  6. Copyright (C) 1993  Shadow Systems   All rights reserved.
  7.  
  8. Registration fee: $ 49.95 (US) Check or Money Order per user.
  9.                   Illinois residents add 8.25% sales tax.
  10.  
  11. Registered users receive free updates, a printed manual, and technical support.
  12. No technical support will be given to unregistered users.
  13.  
  14.  
  15. Mail payment to:  
  16.  
  17. U.S.A.            Shadow Systems       
  18.                   PO Box 486520
  19.                   Niles, IL 60714
  20.                   USA
  21.                   (312) 774-9609
  22.  
  23. Europe            SOFTSOL                    Tel.:+49-40-7665764
  24.                   Salzburger Haeuser 4       Fax :+49-40-7665664
  25.                   2100 Hamburg 90            BBS :+49-40-7665527/8
  26.                   Germany                    CIS :100112,3401
  27.  
  28. IBM PC Support, System/38 and AS/400 are trademarks of IBM Corp.
  29. dBase III and dBase IV are trademarks of Ashton Tate.
  30.  
  31. This program is not Public Domain.  This program is released as shareware.
  32.  
  33. This program may be distributed in any fashion provided the following terms are
  34. met:
  35.     The program is not to be sold.
  36.     The program is not to be included as part of or sold in conjunction
  37.       with any other product.
  38.     No fee or price is to be charged for this product except a service fee
  39.       not to exceed $ 3.00 for copying and handling.
  40.     All three files: SHADOW.EXE, SHADOW.DOC, and SHADOW.LIC must be
  41.       distributed in a single archive file using any of the various
  42.       archive formats (ZIP, ARC, ARJ, etc.) or on a single floppy disk.
  43.       The archive must be named SHADOW.ZIP, SHADOW.ARC, etc.
  44.     Neither the program or the documentation shall be modified in any
  45.           fashion.
  46.  
  47. You may evaluate this product for thirty days.  After thirty days, if you
  48. continue to use this product, you are required to register your    copy and pay
  49. the registration fee.
  50.  
  51. Business users:
  52.     Business use of this program is restricted to registered users only.
  53.     Use of this unregistered demo version in a business environment is a
  54.     violation of the copyright.  This program may be evaluated on one
  55.     PC in your company for the thirty day period.  Use of this product on
  56.     more than one PC requires purchase of a site license or multiple
  57.     copies.
  58.  
  59. See SHADOW.LIC for site licensing information.
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Chapter 1.  Overview
  71. ********************
  72.  
  73. ShadowLink is a program that converts IBM System/38 and AS/400 database
  74. files to dBase III/IV format.  ShadowLink can be used interactively from
  75. the DOS command line or automatically via personal computer batch file
  76. programs.
  77.  
  78. ShadowLink acts as an extension to IBM's PC Support product.  The file
  79. transfer is performed via PC Support.  The host database file is
  80. transferred to an ASCII format file and a PC File Description File (FDF).
  81. The ASCII format file contains the data from the host database.  The FDF
  82. contains a description of the data.  ShadowLink reads both files and
  83. creates a dBase III/IV file.   As ShadowLink reads the database structure
  84. from the FDF file, it will display each line and notify the user of any
  85. errors that occur.
  86.  
  87. ShadowLink requires no special hardware and will run on any PC capable of
  88. running PC Support.
  89.  
  90. ShadowLink will operate under Windows 3.0 in a DOS session.  (There are
  91. special programs and procedures for running PC Support under Windows 3.0.
  92. Contact IBM for further information.)
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130. Chapter 2.  Setting up the PC Support Transfer Request
  131. ******************************************************
  132.  
  133. To convert the host database file to dBase you must first download the
  134. file to the PC.  Use the RTOPC program provided with PC Support to create a
  135. transfer request.  Complete information about setting up PC Support and the
  136. transfer function can be found in the IBM PC Support Technical Reference
  137. Guide.
  138.  
  139. Files to be converted to dBase must be downloaded to the PC in ASCII
  140. format.  A PC File Description File (FDF) must also be created for
  141. ShadowLink.
  142.  
  143. When setting up the transfer request you should name the PC file with a
  144. filename and the .SDF extender.  The PC File description should be given
  145. the same filename with the .FDF extension.  This will greatly simplify the
  146. use of ShadowLink.
  147.  
  148.       PC filename       FILENAME.SDF
  149.       FDF filename      FILENAME.FDF
  150.  
  151. Remember, when creating the transfer request, you must select the PC file
  152. type of ASCII and reply Yes to the prompt to create a PC File Description
  153. File.
  154.  
  155. When you have created the transfer request, you must execute it to
  156. download the database files to the PC.  Once these files have been created
  157. on the PC, ShadowLink can be used to create a dBase file.
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190. Chapter 3.  Converting Database Files Interactively
  191. ***************************************************
  192.  
  193. ShadowLink uses the two files created by the transfer request to create a
  194. dBase III/IV database.  ShadowLink can be called directly from the DOS
  195. command line.
  196.  
  197.      At the DOS command prompt, enter:
  198.                        shadow filename
  199.  
  200. You should replace "filename" with the name of the file you specified in
  201. the transfer request.  This is the simplest form of the command, and will
  202. use the default file extenders.  ShadowLink will read the files
  203. "filename.sdf" and "filename.fdf" and create the file "filename.dbf".
  204.  
  205. This is the recommended method of using ShadowLink.  You must be sure to
  206. name the files properly when creating the transfer request if you wish to
  207. use this method.
  208.  
  209. If you wish to use your own filenames, you may override the ShadowLink
  210. defaults by specifying each filename.
  211.  
  212.      At the DOS command prompt, enter:
  213.                        shadow  file1.ext  file2.ext  file3.ext
  214.  
  215. In this case "file1.ext" is the FDF file created by PC Support,
  216. "file2.ext" is the ASCII format data file created by PC Support, and
  217. "file3.ext" is the name you have selected for the dBase file created by
  218. ShadowLink.
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250. Chapter 4.  Converting Database Files in Batch
  251. **********************************************
  252.  
  253. As with PC Support, ShadowLink will return errorlevel 20 to your batch
  254. file if an error occurs.  Messages from the program will be displayed with
  255. specific details.  See Chapter 6, "Error Messages" for further information.
  256.  
  257.  
  258.  
  259.  
  260. The following batch file demonstrates the use of ShadowLink with an
  261. unattended/automatic download.
  262.  
  263. e5250ah
  264. if errorlevel 20 goto error
  265.  
  266. startrtr
  267. if errorlevel 20 goto error
  268.  
  269. rtopcb transfer.tto
  270. if errorlevel 20 goto error
  271.  
  272. rmvpcs all /f
  273. if exist invent.dbf erase invent.dbf
  274.  
  275. shadow invent
  276. if errorlevel 20 pause
  277.  
  278. goto exit
  279.  
  280. :error
  281. echo A PC Support error has occurred.
  282.  
  283. :exit
  284.  
  285.  
  286. This program starts the AS/400 PC Support function and executes the
  287. transfer request "transfer.tto".  The transfer request downloads
  288. information from the AS/400 and creates the ASCII format file "invent.sdf"
  289. and the PC File Description File "invent.fdf". If the transfer request
  290. completes normally (not errorlevel 20), PC Support is removed from memory
  291. and any existing dBase file (invent.dbf) is deleted. ShadowLink is then
  292. called to read the files "invent.sdf" and "invent.fdf" and create the file
  293. "invent.dbf".  ShadowLink returns errorlevel 20 if an error occurs.   The
  294. batch file then pauses for user input.  If no error occurs, the batch file
  295. will end normally.
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310. The following batch file demonstrates the use of ShadowLink with
  311. user specified filenames and/or extenders:
  312.  
  313. rtopcb invent.tto
  314. if errorlevel 20 goto exit
  315.  
  316. shadow download.fdf invent.dat invent.dbf
  317. if errorlevel 20 pause
  318.  
  319. :exit
  320.  
  321.  
  322. This program assumes that the PC Support function is active and executes
  323. the transfer request "invent.tto".  The transfer request downloads
  324. information from the AS/400 and creates the ASCII format file "invent.dat"
  325. and the PC File Description File "download.fdf". If the transfer request
  326. completes normally (not errorlevel 20), any existing inventory dBase file
  327. (invent.dbf) is deleted.  ShadowLink is then called to read the files
  328. "download.fdf" and "invent.dat" and create the file "invent.dbf".
  329. ShadowLink returns errorlevel 20 if an error occurs.   The batch file then
  330. pauses for user input.  If no error occurs, the batch file will end
  331. normally.
  332.  
  333. In this case, PC Support is not removed from memory and the connection to
  334. the AS/400 is not terminated.
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370. Chapter 5.  Host System Considerations
  371. **************************************
  372.  
  373. ShadowLink operates entirely on the PC side of the host-to-PC link.  PC
  374. Support is the method used for connection to the 3x/400 system.  Therefore,
  375. all security and authorizations are controlled by the host security
  376. configuration.  No host software or special configuration is required.
  377.  
  378. ShadowLink will have no effect on midrange system performance if it is used
  379. after the host connection has been terminated.  If ShadowLink is used
  380. during an online connection it will require a portion of the PC resources.
  381. This in turn may effect communication between the host system and the PC.
  382.  
  383. ShadowLink is compatible with AS/400 PC Support Shared Folders and may be
  384. distributed over a LAN.  However, a site license is required before
  385. operating in either environment.
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430. Chapter 6.  Error Messages
  431. **************************
  432.  
  433. 00 - A PCFDF entry was not found in the FDF
  434.    - The PC File Description File does not contain a PCFDF entry as the first
  435.      line. This entry is required.  Any comment lines preceding the PCFDF entry
  436.      must begin with an asterisk (*) in the first position.  The PCFDF entry
  437.      must begin in the first position of the line.
  438.  
  439. 01 - A "PCFT 1" entry was not found in the FDF
  440.    - The PC File Description File does not contain a PCFT 1 entry.  This entry
  441.      is required.  Any comment lines preceding the PCFT 1 entry must begin with
  442.      an asterisk (*) in the first position.  The PCFT 1 entry must begin in the
  443.      first position of the line.
  444.    - The transfer request did not have ASCII format specified (type 1).
  445.  
  446. 02 - Unexpected error in PCFL line.
  447.    - The format of the PCFL line did not match an expected format.  Acceptable
  448.      formats examples:
  449.           PCFL FIELD 1 1
  450.           PCFL FIELD 2 3/1
  451.           PCFL FIELD 2 1 quantity on hand
  452.           PCFL FIELD 2 3/1 quantity on hand
  453.  
  454. 03 - Unexpected error in the ASCII file.
  455.    - A record which exceeds the record length specified in the FDF has been
  456.      encountered.  Make sure the ASCII file selected matches the FDF file
  457.      selected.
  458.  
  459. 04 - Invalid number of parameters specified.
  460.    - ShadowLink accepts only one or three parameters.
  461.  
  462. 05 - Unable to open FDF.
  463. 06 - Unable to open SDF file.
  464.    - One of the data files specified could not be found.  Move the file to the
  465.      current directory or specify the path as part of the filename.
  466.      (ex. shadow c:\pcs\invent)
  467.  
  468. 07 - Unable to create dBase file, read only?
  469.    - If an existing dBase file is set for read only, ShadowLink will not be
  470.      able to overwrite it.
  471.    - The maximum number of entries in the root directory may have been
  472.      reached.
  473.    - Possible hardware failure or data corruption.
  474.  
  475. 08 - Insufficient memory.
  476.    - The system does not have enough memory for ShadowLink.  The minimum
  477.      memory requirement is 32K, but may vary with record length.  Reboot the
  478.      computer or remove memory resident programs.
  479.  
  480. 09 - Error writing to dBase file, disk full?
  481.    - The file cannot be written to the destination disk.  The disk may be full.
  482.    - Possible hardware failure or data corruption.
  483.  
  484. 10 - The record length exceeds the dBase limit.
  485.    - dBase has a record limit of 4000 bytes.  Modify the transfer request to
  486.      select fields from the host database such that the record length does not
  487.      exceed the dBase limit.
  488.  
  489.  
  490. 11 - The number of fields in the file exceeds the dBase limit.
  491.    - dBase has a limit of 256 fields.  Modify the transfer request to select
  492.      fields from the host database such that the number or fields does not
  493.      exceed the dBase limit.
  494.  
  495. 12 - The field length exceeds the dBase limit.
  496.    - dBase character fields may not exceed 254 characters.  Numeric fields may
  497.      not exceed 19 digits including the decimal point and sign.  Modify the
  498.      transfer request to omit the fields which exceed the dBase limits.  Use the
  499.      FDF conversion program to reformat the file structure (see Appendix A).
  500.  
  501. 13 - The number of decimals in the field exceeds the dBase limit.
  502.    - dBase restricts the number of decimals in a numeric field to 15.  The
  503.      number of decimals must also be at least 2 less than the field length.
  504.      Modify the transfer request to omit the fields which exceed the dBase
  505.      limits.  Use the FDF conversion program to reformat the file structure (see
  506.      Appendix A).
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550. Appendix A    Converting the FDF for dBase Compatibility
  551. ********************************************************
  552.  
  553. The PC File Description File created by the PC Support Transfer Function
  554. may contain fields which are incompatible with dBase III/IV.  ShadowLink
  555. will automatically rename fields whose names contain characters not allowed
  556. by dBase.  Additional data errors may occur that ShadowLink will not
  557. correct.
  558.  
  559. Fields which exceed the dBase limits for size or number of decimals will
  560. cause ShadowLink to generate an error message.  When one of these errors
  561. occurs, the FDF may be modified to dBase requirements.
  562.  
  563. Before attempting to change the FDF copy the file to another directory so
  564. that you have a backup copy.  The original FDF will be required if you wish
  565. to upload the dBase data back to the host system (see Appendix B).  To
  566. modify the FDF you will need some sort of text editor or the DOS EDLIN.  If
  567. you wish to use a word processor, it must be able to read and write an
  568. ASCII document file.
  569.  
  570. If the field in error is a character field with length greater than 254
  571. (error 12):
  572.  
  573. Locate the field in the FDF causing the error message.
  574. Replace the line in error with multiple lines as shown:
  575.  
  576.        PCFL  FIELD  1  510
  577.  
  578.   becomes:
  579.        PCFL FIELDA  1  200
  580.        PCFL FIELDB  1  200
  581.        PCFL FIELDC  1  110
  582.  
  583. Note that the combined length of the new fields equals the length of the
  584. original field and each of the fields must be type 1 (character) and have a
  585. unique name.
  586.  
  587. If the field in error is a numeric field with length greater than 19 (error
  588. 12) or if the number of decimals exceeds the dBase limits (error 13):
  589.  
  590. Locate the field in the FDF causing the error message.
  591. Change the field type from 2 (numeric) to 1 (character) and remove any
  592. decimal specifications.
  593.  
  594. example:
  595.        PCFL FIELD  2  3/1
  596.   becomes:
  597.        PCFL FIELD  1  3
  598.  
  599. This causes the field to be retyped as character and thus not subject to
  600. the numeric field limitations.  This does however, mean that the field may
  601. no longer be manipulated with numeric operators in dBase.
  602.  
  603. Any changes to the FDF cause it to be incompatible with the host system
  604. database.  Be sure to maintain a copy of the original FDF if upload to the
  605. original host datbase may be required.
  606.  
  607. The FDF entries may also be modified to adjust field lengths for changes
  608. made via dBase.  The modified FDF may then be used to upload to the host
  609. system.